---
id: docs-intro
slug: /
sidebar_position: 1
sidebar_label: Introduction
---

# OrioleDB: The next-generation storage engine for PostgreSQL

OrioleDB is a **storage extension for PostgreSQL** which uses PostgreSQL's pluggable storage system.

It is designed to be a drop-in replacement for PostgreSQL's existing storage engine. OrioleDB is built to take advantage of modern hardware and cloud infrastructure, providing better performance and scalability for PostgreSQL workloads.

## Example

OrioleDB uses Postgres Table Access Method (TAM) to provide a pluggable storage engine for PostgreSQL. Here is an example of how you can create a table using OrioleDB:

```sql
-- Enable the OrioleDB extension
CREATE EXTENSION orioledb;

CREATE TABLE blog_post
(
  id int8 NOT NULL,
  title text NOT NULL,
  body text NOT NULL,
  PRIMARY KEY(id)
) USING orioledb; -- Use the OrioleDB storage engine
```

## Pluggable Storage in PostgreSQL

Pluggable Storage gives developers the ability to use different storage engines for different tables within the same database. Developers will be able to choose a storage method that is optimized for their specific needs: some tables could be configured for high transactional loads, others for analytics workloads, and still others for archiving.

<details>
<summary>See examples</summary>

```sql
create table analytics_data
(
  id int8,
  created_at timestamptz,
  event text
) using parquet; -- Store data in a analytical optimized storage engine

create table timeseries_data
(
  id int8,
  created_at timestamptz,
  event text
) using timeseries; -- Store data in a time-series optimized storage engine
```

</details>

Something like this is already available in MySQL, which uses the `InnoDB` as the default storage engine since MySQL 5.5 (replacing `MyISAM`). Read more about the history of pluggable storage [here](https://supabase.com/blog/postgres-pluggable-strorage).

## Using OrioleDB with existing PostgreSQL installations

OrioleDB currently requires a set of patches to PostgreSQL to enhance the pluggable storage API and other PostgreSQL subsystems. All of these patches have been submitted to the PostgreSQL community and are under review.

The important property of this set of patches is keeping the binary compatibility.  That is, you can switch to the patched PostgreSQL binary while keeping the same data directory.  The existing tables will continue working with the default `heap` engine until you switch them to use `orioledb`.  Moreover, it's possible to switch back to using unpatched PostgreSQL binaries.  You would just need to convert your `orioledb` tables back to heap before.

The goal is to upstream everything: once these patches are accepted, OrioleDB will be able to run on any PostgreSQL installation without any modifications. This will also enable the entire PostgreSQL community to create their own pluggable storage engines.

Until then, you can use our [pre-built Docker image](https://hub.docker.com/r/orioledb/orioledb) to try out OrioleDB. The Docker image includes a patched version of PostgreSQL with OrioleDB pre-installed. Follow the [Getting started](usage/getting-started.mdx) guide to get started.

## Patch set

You can get the full set of patches [here](https://github.com/orioledb/postgres/commits/patches16/).
The following patches have been submitted to the PostgreSQL community to enhance the TAM interface and other subsystems.

|                    | Name                                                              | Link                                                                                         | Version          |
| ------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------------- |
| :white_check_mark: | Add missing inequality searches to rbtree                         | [Link](https://github.com/postgres/postgres/commit/e57519a4637a8d88ae993ac1273d2b59d03a0f75) | PostgreSQL 16    |
| :white_check_mark: | Document the ability to specify TableAM for pgbench               | [Link](https://github.com/postgres/postgres/commit/f77ff083350eb5a2625a4dbfca61d15b66c4918b) | PostgreSQL 16    |
| :white_check_mark: | Remove Tuplesortstate.copytup function                            | [Link](https://github.com/postgres/postgres/commit/d47da3162b4d77c888c895dd36e4ef9cb92fcf19) | PostgreSQL 16    |
| :white_check_mark: | Add new Tuplesortstate.removeabbrev function                      | [Link](https://github.com/postgres/postgres/commit/cadfdd1edff103d696bbfcdd126c2dee516aed9b) | PostgreSQL 16    |
| :white_check_mark: | Put abbreviation logic into puttuple_common()                     | [Link](https://github.com/postgres/postgres/commit/033dd02db2248ed792332b950431ced4771b8304) | PostgreSQL 16    |
| :white_check_mark: | Move memory management away from writetup() and tuplesort_put*()  | [Link](https://github.com/postgres/postgres/commit/097366c45f5dfe142eb232dc6d348ca0705a63a9) | PostgreSQL 16    |
| :white_check_mark: | Split TuplesortPublic from Tuplesortstate                         | [Link](https://github.com/postgres/postgres/commit/ec92fe98356a8a36427fe9ef52873b50fe17852e) | PostgreSQL 16    |
| :white_check_mark: | Split tuplesortvariants.c from tuplesort.c                        | [Link](https://github.com/postgres/postgres/commit/d0b193c0fad13cf35122b0d3dc805c76e323e8bf) | PostgreSQL 16    |
| :white_check_mark: | Fix typo in comment for writetuple() function                     | [Link](https://github.com/postgres/postgres/commit/924954c670355f2a0ca1dd4173574a28fc0eedec) | PostgreSQL 16    |
| :white_check_mark: | Support for custom slots in the custom executor nodes             | [Link](https://github.com/postgres/postgres/commit/cee120951427fe39a54ab800abfa2834d85b8771) | PostgreSQL 16    |
| :email:            | Allow table AM to store complex data structures in rd_amcache     | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Allow table AM tuple_insert() method to return the different slot | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Add TupleTableSlotOps.is_current_xact_tuple() method              | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Allow locking updated tuples in tuple_update() and tuple_delete() | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Add EvalPlanQual delete returning isolation test                  | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Generalize relation analyze in table AM interface                 | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Custom reloptions for table AM                                    | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |
| :email:            | Let table AM insertion methods control index insertion            | [Link](https://commitfest.postgresql.org/48/4958/)                                           | PostgreSQL 18    |

##### Legend

:white_check_mark: - Patch has been accepted.<br />
:email: - Patch is submitted and under review by the PostgreSQL community.<br />
:pencil2: - Patch is being worked on.<br />

## Features

OrioleDB opens the door to a future of more powerful storage models that are optimized for cloud and modern hardware architectures.

### Open source

OrioleDB is distributed under the standard PostgreSQL license. The goal is to upstream all the patches required to run OrioleDB on any PostgreSQL installation without any modifications.

### Designed for modern hardware

OrioleDB design avoids legacy CPU bottlenecks on modern servers containing dozens and hundreds CPU cores, providing optimized usage of modern storage technologies such as SSD and NVRAM.

### Reduced maintenance needs

OrioleDB implements the concepts of undo log and page-mergins, eliminating the need for dedicated garbage collection processes. Additionally, OrioleDB implements default 64-bit transaction identifiers, thus eliminating the well-known and painful wraparound problem.

### Designed to be distributed

OrioleDB implements a row-level write-ahead log with support for parallel apply. This log architecture is optimized for raft consensus-based replication allowing the implementation of active-active multimaster.

## Differentiators

The key technical differentiations of OrioleDB are as follows:

### No buffer mapping and lock-less page reading

In-memory pages in OrioleDB are connected with direct links to the storage pages. This eliminates the need for in-buffer mapping along with its related bottlenecks. Additionally, in OrioleDB in-memory page reading doesn't involve atomic operations. Together, these design decisions bring vertical scalability for Postgres to the whole new level.

### MVCC is based on the UNDO log concept

In OrioleDB, old versions of tuples do not cause bloat in the main storage system, but eviction into the undo log comprising undo chains. Page-level undo records allow the system to easily reclaim space occupied by deleted tuples as soon as possible. Together with page-mergins, these mechanisms eliminate bloat in the majority of cases. Dedicated VACUUMing of tables is not needed as well, removing a significant and common cause of system performance deterioration and database outages.

### Copy-on-write checkpoints and row-level WAL

OrioleDB utilizes copy-on-write checkpoints, which provides a structurally consistent snapshot of data every moment of time. This is friendly for modern SSDs and allows row-level WAL logging. In turn, row-level WAL logging is easy to parallelize (done), compact and suitable for active-active multimaster (planned).

## Resources

### Hacker news

- [OrioleDB - solving some PostgreSQL wicked problems](https://news.ycombinator.com/item?id=30462695)
- [PostgreSQL: No More Vacuum, No More Bloat](https://news.ycombinator.com/item?id=36740921)
- [OrioleDB Reached Beta](https://news.ycombinator.com/item?id=36392765)

### Solving PostgreSQL Wicked Problems

This talk covers how the new engine is integrated with PostgreSQL Core and solves the wicked PostgreSQL problems.

<div
  style={{
    position: "relative",
    width: "100%",
    paddingBottom: "56.25%",
    height: 0,
  }}
>
  <iframe
    style={{
      position: "absolute",
      top: 0,
      left: 0,
      width: "100%",
      height: "100%",
    }}
    src="https://www.youtube-nocookie.com/embed/coaJCB_H9cU?si=MHdGlhg-KOAPRlQ8"
    title="YouTube video player"
    frameBorder="0"
    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
    referrerPolicy="strict-origin-when-cross-origin"
    allowFullScreen
  ></iframe>
</div>
